/*******************************************************************************
 * Venice Noise Android Application
 * Copyright (C) 2011  Worcester Polytechnic Institute, Wesley Ripley
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; version 2
 * of the License
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 * 
 * If you plan to use or modify any of this code please contact Fabio Carrera (carrera.fabio@gmail.com)
 * Also please attribute any code used in the final product to the developers. 
 * 
 * Author: Wesley Ripley (wripley@wpi.edu) 
 *******************************************************************************/
package org.venicenoise.app.location;

import android.location.Location;

/**
 * A interface for getting location information from this device
 * @author Wesley Ripley
 * @version 12/16/2011
 */
public interface LocationService extends LocationChangedListenable{

	/**
	 * Start trying to locate where the device is
	 */
	public void startLocating();
	
	/**
	 * Stop locating or updating the location of the device
	 */
	public void stopLocating();
	
	/**
	 * Whether or not this service is actively trying to locate this device
	 * @return
	 * 		true if this LocationService is currently looking for its location, false otherwise
	 */
	public boolean isLocating();
	
	/**
	 * Whether or not the location of this device has been found
	 * @return
	 * 		true if a location has been found, false otherwise
	 * 		(isLocating() must return true for this function to ever return true)
	 */
	public boolean locationAvailable();
	
	/**
	 * Get the current best estimate for the location of this device
	 * Returned location should be safe to modify without affecting
	 * the LocationService
	 * @return
	 * 		The current best estimate for the location of this device
	 */
	public Location getLocation();
	
}
